From 6a1cb3304b0abf3d20541c48f889c4bbc6fa776f Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 20 Oct 2020 18:26:38 -0400 Subject: [PATCH] docs: Mention subclassing and destroy in the migration guide Mention changes regarding subclassing and life-cycle handling in the migration guide. --- docs/reference/gtk/migrating-3to4.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md index 6ce96a8878..44f7d785b9 100644 --- a/docs/reference/gtk/migrating-3to4.md +++ b/docs/reference/gtk/migrating-3to4.md @@ -239,6 +239,31 @@ you get to the point that you actually build your application against GTK 4. Making it possible to prepare for these in GTK 3 would have been either impossible or impractical. +### Larger changes + +Some of the larger themes of GTK 4 development are hard to cover in the form +of checklist items, so we mention them separately up-front. + +#### Subclassing + +Compared to previous versions, GTK 4 emphasizes composition and delegation +over subclassing. As a consequence, many widgets can no longer be subclassed. +In most cases, you should look deriving your widget directly from GtkWidget +and use complex widgets as child widgets instead of deriving from them. + +#### Life-cycle handling + +Widgets in GTK 4 are treated like any other objects - their parent widget +holds a reference on them, and GTK holds a reference on toplevel windows. +gtk_window_destroy() will drop the reference on the toplevel window, and +cause the whole widget hierarchy to be finalized unless there are other +references that keep widgets alive. + +The #GtkWidget::destroy signal is emitted when a widget is disposed, and +therefore can no longer be used to break reference cycles. A typical sign +of a reference cycle involving a toplevel window is when closing the window +does not make the application quit. + ### Stop using GdkScreen The GdkScreen object has been removed in GTK 4. Most of its APIs already -- 2.30.2